Tools Plus supports the use of buttons on any Tools Plus window. Buttons are created on the current window by the NewButton procedure. Each button is referenced by a unique button number, which can be from 1 to 255. This number is specified when the button is created, and refers to the specific button until that button is deleted. Note that the button number is related to its associated window. This means that two different windows can each have a button numbered “1” without interfering with each other. Whenever a button is clicked by the user, the PollSystem function reports the button number as well as its window number.
When a button is no longer required, it is deleted by the DeleteButton procedure, which releases the memory used by that button. This is done automatically if a window is closed. Buttons can be renamed by using the ButtonTitle procedure.
Button Types
````````````
All three types of Macintosh buttons are supported by Tools Plus (push-button, radio button and check-box). The push-button is clicked when the user wants to select it. A push button is always used to “do something right now,” such as confirming or canceling a process.
Check boxes and radio buttons are variations on a similar theme: they can be either selected or deselected by clicking on them. The check box contains and “x” when checked, whereas the radio button contains a dot. The difference between these two buttons is that radio buttons are logically grouped by your application such that only one button can be selected within the group. When the user selects a radio button, your application de-selects the other buttons in the group.
Button States
`````````````
All three button types can be either enabled or disabled by using the EnableButton procedure. When a button is disabled, it becomes dim and cannot be selected by the user. Check boxes and radio buttons can be either selected or de-selected by using the SelectButton procedure.
When a window is inactive, all the associated buttons are automatically disabled and cannot be selected. When the window is activated, the buttons are automatically returned to their normal state as set by your application.
Button Titles
`````````````
A button’s title can be changed by the ButtonTitle procedure, however this should be done judicially since this can be confusing to the user. A button’s title is centered in a push button, and left aligned in a check box or radio button.
Fonts
`````
When a button is created, the window’s current font, size and style settings (as set by the TextFont, TextSize, and TextFace procedures) are remembered by the button. The window’s settings can then be changed without affecting the button. Unlike regular buttons, Tools Plus buttons can each have a different font.
Default Button
``````````````
One push button on each window can be designated to be the “default” button by the SetDefaultButton procedure. This procedure draws an outline around the button. If the Return or Enter key is pressed, Tools Plus responds as if the default button had been clicked. The button’s default status can be cleared by the NoDefaultButton procedure. A default button cannot be created on a tool bar or floating palette.
When the user is working in an editing field, only the Enter key invokes the default push button. This is done to avoid confusion between fields that can and cannot accept the Return key as a carriage return in the field.
Handling Buttons
````````````````
Your application specifies if check boxes or radio buttons are selected or not. It also specifies if a button is enabled or disabled. When a window in inactive, Tools Plus disables all buttons on that window. When the window is activated again, all the buttons regain their correct status as specified by your application.
The PollSystem function is used to constantly inquire about any events that have occurred, including clicking on buttons. If a button is selected (i.e. the user presses the mouse button down and releases it within the button’s region), it is reported by PollSystem. This also applies if the user presses the Enter or Return key when a window has a default button. In the case of check boxes or radio buttons, your application must then select or de-select the button appropriately.
When working with Radio Buttons, Tools Plus doesn’t know how these buttons are grouped, and therefore does not automatically turn off other radio buttons. Your application must handle this.
Warning: If you have obtained a handle to a button, do not change any of
Button specifies the button number (from 1 to 255) that is created in the current window. Once a button is created, it is referenced by this button number. If a button has been previously created in the current window using the same number, it is replaced with a new button as specified by the parameters in the NewButton procedure. If the current window doesn’t belong to your application, or if no windows are open, NewButton does nothing.
Left, top, right, and bottom define a rectangle in local co-ordinates that determines the button’s size and location in the window. These parameters can be seen as two corners; the upper left-hand corner (left,top) and the bottom right-hand corner (right,bottom). See the chart below regarding the minimum height for buttons. These measurements are based on using the system font (Chicago) for the button’s text.
Minimum Height Standard
With Descenders No Descenders Height
Push Buttons 18 13 20
Radio/Check Box Buttons 14 12 16
The Title parameter is the button’s title. Each button should have a unique title. Button titles can have multiple lines, each line being separated by the ASCII character code $0D (carriage return). It is your responsibility to ensure that the rectangle defining the button’s co-ordinates is sufficient to contain the button’s title.
ProcID is the button definition ID, which specifies the button’s appearance and behavior. The following are the three standard button definitions.
pushButProc = push-button
checkBoxProc = check box
RadioButProc = radio button
The EnabledFlag indicates if the newly created button is enabled or not. All three button types can be either enabled or disabled. When a button is disabled, it becomes dim and cannot be selected by the user. All buttons automatically become disabled when the window containing them is inactive. When the window is activated, the buttons assume their state as set by the NewButton procedure and subsequent calls to the EnableButton procedure. The two constants that can be used for this flag are enabled and disabled.
The SelectedFlag indicates if the newly created button is selected or not. Only check boxes and radio buttons can be selected (this setting has no effect on push buttons). The two constants that can be used for this flag are selected and notSelected.
Fonts
`````
By default, all buttons are drawn using the system font (Chicago, 12 point). Buttons can also be drawn using the window’s current font, size and style settings (as set by the TextFont, TextSize, and TextFace procedures) by adding the constant useWFont to the procID (i.e. pushButProc + useWFont). When a button is created, the window’s current font, size and style settings are remembered by the button. The window’s settings can then be changed without affecting any buttons. The button’s font, size, and style cannot be changed without recreating the button.
Default Button
``````````````
When specifying the ProcID, you can optionally make one of the push buttons the “default” for the window. The default button is automatically selected if the user presses the “Return” key or “Enter” key. To make a button the default, specify a ProcID of pushButProc + DefaultButton, or simply use DefaultButton as a procID. A black outline is drawn around the default button. The outline is automatically grayed out whenever the default button is disabled. A default button cannot be created on a tool bar or floating palette.
If a default button already exists in the current window and you specify another button, the original one loses its “default” status. Note that only 1 button can be the default in each window, and that it must be a push button.
Note: Tools Plus makes no attempt to control the placement of buttons or
to protect them once they have been created. It is the
programmer’s responsibility to ensure that buttons are of
sufficient size to contain their title, and that their placement
within the window is reasonable and does not conflict with other
objects. Furthermore, you should not allow the application’s text
and drawing processes to interfere with buttons, or with the
“default button” frame. Windows with a “size box” should not
allow buttons to be obscured or hidden by making the window too
small.
Also see: NewButtonRect.
CONST {Button definition IDs }
pushButProc =0; {Push button }
checkBoxProc =1; {check box }
RadioButProc =2; {radio button }
DefaultButton=4; {default push button (1 only per window) }
useWFont =8; {added to ProcID to use the window’s font}
NewButtonRect is identical to the NewButton procedure, except that it accepts the Bounds rectangle in place of the individual left, top, right and bottom co-ordinates.
Button specifies the button number (from 1 to 255) that is deleted from the current window. If the current window doesn’t belong to your application, or if no windows are open, or if the button does not exist in the current window, DeleteButton does nothing.
Button specifies the button number (from 1 to 255) that is affected in the current window. If the current window doesn’t belong to your application, or if no windows are open, or if the button does not exist in the current window, EnableButton does nothing.
The EnabledFlag indicates if the button is enabled or not. All three button types can be either enabled or disabled. When a button is disabled, it becomes dim and cannot be selected by the user. All buttons automatically become disabled when the window containing them is inactive. When the window is activated, the buttons assume their state as set by the NewButton procedure, and subsequent calls to the EnableButton procedure. The two constants that can be used for this flag are enabled and disabled.
CONST {Button state }
enabled =true; {button is enabled }
disabled =false; {button is disabled }
See the NewButton procedure for additional information pertaining to the button’s enabling, disabling, and selection (i.e. checked or not).
Button specifies the button number (from 1 to 255) that is affected in the current window. If the current window doesn’t belong to your application, or if no windows are open, or if the button does not exist in the current window, SelectButton does nothing.
The SelectedFlag indicates if the button is selected (checked) or not. Only check boxes and radio buttons can be selected. This setting has no effect on push buttons. The two constants that can be used for this flag are selected and notSelected.
CONST {Button state }
selected =true; {button is selected (checked) }
notSelected =false; {button is not selected (not checked) }
See the NewButton procedure for additional information pertaining to the button’s enabling, disabling, and selection (i.e. checked or not).
function ButtonIsEnabled(Button: INTEGER): BOOLEAN;
Button specifies the button number (from 1 to 255) which is queried in the current window.
The function’s value returns true if the button is enabled, and false if the button is disabled. If the current window doesn’t belong to your application, or if no windows are open, or if the button does not exist in the current window, ButtonIsEnabled returns false.
CONST {Button state }
enabled =true; {button is enabled }
disabled =false; {button is disabled }
See the NewButton procedure for additional information pertaining to the button’s enabling, disabling, and selection (i.e. checked or not).
Note: ButtonIsEnabled returns the button’s state as though the button’s
window is active. This is the case even when the window is
function ButtonIsSelected(Button: INTEGER): BOOLEAN;
Button specifies the button number (from 1 to 255) that is queried in the current window.
The function’s value returns true if the button is selected (checked), and false if the button is not selected. If the current window doesn’t belong to your application, or if no windows are open, or if the button does not exist in the current window, ButtonIsSelected returns false.
CONST {Button state }
selected =true; {button is selected (checked) }
notSelected =false; {button is not selected (not checked) }
See the NewButton procedure for additional information pertaining to the button’s enabling, disabling, and selection (i.e. checked or not).
Button specifies the button number (from 1 to 255) that is affected in the current window. If the current window doesn’t belong to your application, or if no windows are open, or if the button does not exist in the current window, ButtonTitle does nothing.
The Title parameter is the button’s title. Each button should have a unique title. Button titles can have multiple lines, each line being separated by the ASCII character code $0D (carriage return). Note that a button’s size does not change automatically to accommodate larger or smaller titles.
Flash a button as though it was clicked by the user.
pascal void FlashButton (short Button);
procedure FlashButton(Button: INTEGER);
Button specifies the button number (from 1 to 255) that is affected in the active window. If the active window doesn’t belong to your application, or if no windows are open, FlashButton does nothing.
FlashButton can be used in some specific instances. Advanced programmers may decide to display a modal window when the Macintosh is busy with a lengthy process. If a button (such as “Cancel”) on this window is equivalent to typing Command-., the button should be flashed when a Command-. is reported by PollSystem. This makes the user feel that the key triggered the button. Another example is double-clicking in a list box; this action can be interpreted as “select line and OK” in which case the OK button should be flashed. This also occurs if your application interprets double-clicking a radio button as “select button and OK.”
Button specifies the button number (from 1 to 255) that will become the new default button in the current window. If the current window doesn’t belong to your application, or if no windows are open, SetDefaultButton does nothing. Also, if Button specifies a button that is not a push button, or a button that does not exist, SetDefaultButton does nothing. A default button cannot be set on a tool bar or floating palette.
The default button is automatically selected if the user presses the “Return” key or “Enter” key. A black outline is automatically drawn around the default button when the window is active. If another default button already exists in the current window, it loses its “default” status. Note that only 1 button can be the default in each window.
This procedure removes the “default button” status from the current window (i.e. a specific button will not be automatically selected when the user presses the “Return” key or “Enter” key). The black outline that is automatically drawn around the default button is removed. Buttons themselves, however, are not altered. If the current window doesn’t belong to your application, or if no windows are open, NoDefaultButton does nothing.
